Chip: Net Guide

home *** CD-ROM | disk | FTP | other *** search

/ Chip: Net Guide / CHIP NET Rehberi Eylül 1998.iso / ftp / iftp21 / IFTPCODE.TXT < prev next >

Wrap

Text File | 1998-06-29 | 69.9 KB | 2,012 lines

iFTP "Intelligent FTP" Version 2.1d (c) copyright 1997-1998 Santronics Software Inc contact: support@santronics.com Updated: May 6, 1998 ================================= iFTP Script Language Introduction ================================= iFTP offers a powerful, yet easy to learn, enhanced FTP script language to create and run sophiscated and robust FTP automated sessions. The #1 clear enhancement of iFTP over typical standard FTP commands is the extra script commands in iFTP to perform logical conditions and copy/move from a target to source with the ability to check for errors. But iFTP is basically a "DOS LIKE" language with many similar capabilities that you have in DOS batch files. iFTP views the remote ftp site as a "special drive" ftp: which you can use to distinguish which directories are being used, local DOS drive or the remote FTP "drive". A powerful example of how you can use the iFTP script language is the ability to check for the existence of a file before proceeding with more commands, or you may wish to download multiple files and delete each file if the file download is successful, thus preventing duplicate downloads during restarts. The iFTP script language offers similar standard FTP commands but enhanced and easier to use. For example, the FTP get and mget commands were combined as one extended GET command; you can define you host name, userid and password all on the same OPEN command; and you can call other scripts recursively. You can use the new COPY or MOVE commands like in DOS to perform file transfers. iFTP scripts are flat ascii text files which you can create using a normal text editor. Example Scripts: examples.zip contains an assortment of examples using the iFTP script language. ftphub.zip contains a batch file and script to handle the FTP HUB operations for Platinum Xpress Customers with George Peace ihub.zip contains a batch file and script to handle the FTP HUB operations for Platinum Xpress Customers with John Souvestre ============================================================ Requires iFTP Files, Log file and Script locations ============================================================ In order to run iFTP, the follow files are required (bare mininum) in the same location IFTP.EXE is located: iftp.exe iftp.ini (required) INI file for iFTP ssreg.ini (required) Registration file iftphelp.txt (optional) For console mode help display wininet.dll (required) Microsoft's Winsock Internet Library iFTP can be placed in a PATH directory and iFTP will automatically use the complete IFTP.EXE directory location to read the above files. iFTP.INI will be searched first in the current directory. If not found, the iFTP.INI must be located in the iftp.exe program directory. If not found, an error will be reported. WININET.DLL Microsoft' Winsock Internet Library ----------------------------------------------------- The iFTP package comes with WININET.ZIP. It contains Microsoft's Winsock internet library file WININET.DLL. iFTP is based on this library and it is required in order to run. If it is not found, you will get a Windows Popup message saying it was not found. You may already have this file in your Windows System directory since it comes with NT 4.0, IE 4.0 and all the new Microsoft software. So if you already have this special WININET.DLL file, you don't need to unzip WININET.ZIP. To quickly find out if you need it or not, simply type IFTP at the DOS BOX and if you see Windows immediately returns a pop up error message: "Application Requires WININET.DLL" or "Missing WININET.DLL" or something close to that effect, then you don't have on your system and you will need to unzip the WININET.ZIP file. You can keep it WININET.DLL in the IFTP directory or you can copy it over to the Windows System directory. Either way will work. However, if you ever do install IE 4.0 or NT 4.0 or any of the new Microsoft software, the odds are very good it will come with their current version of WININET.DLL and they might be some conflicts if IE 4.0 is using its version and iFTP is using an older version. So our recommendation is to copy the WININET.DLL file to the Windows System Directory and make sure there isn't a second copy any where is on your system. Delete the copy in the IFTP directory. There will never be a problem unless there are different versions of this library loaded into memory by different applications. By copying it into the Windows System directory, you will make sure all Win32 applications who need this library will find and use the same version of the file. If IE 4.0 installs a new one, then IFTP benefits from using this new version (we hope so). iFTP Script file Location ------------------------- When running scripts, by default iFTP looks for script (without a directory path) in this order: - Current directory, - IFTP.EXE directory, - The directory defined by the AltScriptPath= key word in the IFTP.INI [Setup] section. If a script file has a specific directory on it, then it expects the script to be specifically at the location defined. The above search is only done if just a file name is provided (with no directory). By default, iFTP will use the file extension "FTP" for all scripts. iFTP is a powerful script system. Hence it is very possible that you will or can create many generic scripts which can be reused but other scripts. You can store these either in the IFTP directory or use the AltScriptPath= to define a directory where you place your generic scripts. iFTP.INI Configuration File --------------------------- iFTP will automatically read the iFTP.INI file for system configuration options and account setups. The INI file is a typical "Windows Based" INI file, with sections, keys and values. Read the iFTP.INI. The file has self help for all the options. Much information can be found in the INI which may not be found in this guide. iFTP Log File and Script Log Files ---------------------------------- iFTP keeps a very details log of its operations in the log file with a default file name of IFTP.LOG. By default, the log file is created in the same directory location IFTP.EXE is located. This allows you to run IFTP from any where on the harddrive and the IFTP.LOG will always be found in the iFTP directory. There are three ways to change the log file iFTP will use: Using the command line switch, /LOG iFTP /LOG <directory> This allows you to change the directory location where IFTP.LOG will be placed. It does not change the file name. Only the location. Using the INI [SETUP] option LogFilePath= The keyword LogFilePath= in the INI [SETUP] session will define the directory location where IFTP.LOG will be placed. Once again, this does not change the file name. Only the location. Using the script command LOGFILE LOGFILE [filename] The LOGFILE script command is the only way to change the log file name. This command useful when you wish to create a log file for different IFTP script operations. Once the script is finished, the default LOG file is automatically reset (or the last log file defined is reset for situations where you have scripts calling other scripts). Example: The top script call main.ftp calls two other scripts: MAIN.FTP Log Starting Main.ftp........... Call script1.ftp Call script2.ftp Log Done! The individual sub scripts, script1 and script2 has a LOGFILE command at the top of each script to create a specific log file for that script. Like so: SCRIPT1.FTP Logfile script1.log Log Hello! We are now in Script 1 SCRIPT2.FTP Logfile script2.log Log Hello! We are now in Script 2 Once each sub script has finished, iFTP will automatically reset the default log before it reads the next line in the MAIN.FTP script. Use the LOGFILE command when you have multiple scripts which create big logs and you want to separate the operations into their own separate logs for easier reading. ============================== iFTP Script Language Reference ============================== --------------- Language Syntax --------------- All commands that have parameters are either required or optional. The following delimiters are used to define the required or optional parameter. [] optional parameter <> required parameter Comment lines in scripts all begin with the following character(s) on column 1. // Double slash inline comment. ; Semi-colon : Colon ----------------------- General Script Behavior ----------------------- To run a script, use the /RUN command line option, like so: iFTP /RUN getmail.ftp You can also call a script from within a script by using the CALL command. All script files have a default file extension is FTP. So the FTP extension is not required when specifying the script file name. If the extension is different, it must be specified. A iFTP script is a DOS based text file. You can NOTEPAD, the DOS editor called EDIT or your favorite text editor to create script files. When iFTP first reads a script, it starts at the very top and reads down the text, ignoring all comment lines. All scripts end by themselves. Once the last line is encounter, the script ends and iFTP exits. Since iFTP offers the power of calling scripts within scripts, there are several commands to end iFTP or scripts. EXIT [X] Exit current script with optional errorlevel, Does not abort iFTP. Returns to calling script or ends iFTP if top script. The errorlevel, if used, can be detected with the IF ERRORLEVEL X command. QUIT Exit all scripts, ends iFTP, normal end, errorlevel 0 ABORT Exit all scripts, aborts iFTP with errorlevel 1 HALT [X] Exit all scripts, aborts iFTP with optional errorlevel X. The default is 0. Use ABORT when you view the error as critical and you want an simple errorlevel. Use Halt when you want a different error level other than 1. iFTP offers GOTO xxxx commands where it will jump to the script line with the line LABEL xxxx. It can search UP or DOWN the script but only the first line in the script with the LABEL xxxx will be used. In other words, do not define two labels with the same XXXX name. ------------------------------------------------------------ DOS File Names vs Unix File Names (special remote FTP drive) ------------------------------------------------------------ In general, when using some of the iFTP script commands, such as CD, DIR, IF EXIST, COPY, MOVE etc, it is important to understand the difference between DOS file naming vs UNIX file naming to determine which determine the direction the transfer takes place, local to remote (upload) or remote to local (download). The key difference is the usage between the forward slash (/) vs the back slash (\). When specifying file names relative to DOS, use the back slash (\). For example: c:\iFTP\export\*.* When specifying file names relative to UNIX, use the forward slash (/). For example: /inbin/*.* or you can use the special remote drive letter, ftp: ftp:/inbin/*.* Although, iFTP will allow you to use DOS back slashes for UNIX directories and file names in many of the remote file I/O commands, it helps if you understood the distinction. Many of the new iFTP commands rely on this distinction of back slash (/) versus forward slash (/) and using the ftp: drive letter to determine which direction is the file transfer or location of the file. In this document, a file name or directory having unix back slashes, refers to a file or directory at the remote site. Similarily, a file name or directory having DOS back slashes, refers to a file or directory at the local site. Here are some examples: // download from remote /*.* to local \import directory copy /*.* \import // upload all files in \export to remote /import directory copy \export\*.* /import As you can see, iFTP uses the same command, but uses the / or \ to determine the direction. New with Version 2.0! When no relative paths are defined, PX will assume the local drive. However, you can now switch to the remote drive using the FTP: command to make all the FILE I/O commands relative to the remote drive. For example: open ftpsite // show dos directory dir // show remote directory dir / // show remote directory FTP: dir In other words, the FTP: command switches the relative drive to the remote site to make it easier to use the DIR and CD commands. This is very useful when using iFTP in console mode (iFTP /con). =========================================== iFTP Asynchronous vs Synchronous Operations =========================================== When performing FTP operations under Win32, it can done in two modes: - Asynchronous or non-blocking - Synchronous or blocking Blocking basically means that iFTP makes a request and waits for a response. In a non-blocking environment, iFTP will make a request and do something else while waiting for the response. In a non-blocking state, more information is obtained. It has more overhead and thus can be slightly slower (probably not noticable). This concerns iFTP for only two things: - For Debugging, to watch whats going on at various states. - To offer a progress indicator during file transfers. So after its all said and done, the only reason why you would want to use Asynchronous operations is to turn on the progress indicator. Otherwise, when you issue a GET or PUT, iFTP will not log or say anything until the request is complete. Under normal and working script operations, this would be the best mode of operations. Turning on Asynchronous operations iFTP opens the windows internet sockets in async or sync mode based on the initial Socket= value in the iFTP.INI [Setup] session. If 1, the socket will be open up in Asynchronous mode, thus making all FTP commands available for non-blocking operations. However, even if the socket is open in async, you still have the power to turn on various file transfer async modes. You can also use the script command ASYNC to disable or enable asynchronous operations. ASYNC [ON|OFF|CONNECT|GET|PUT|DIR] The Async command toggles Asynchronous operations globally or specific parts of a network session. There are four parts iFTP can perform Asynchronous communications: CONNECT when connection to a ftp host/server GET when downloading files PUT when uploading files DIR when issues a directory command If ON to globally turn on async communications for all four processes, use OFF to turn them off. Since one of the main reasons for asynchronous operations was to allow for a progress indication, the PROGRESS command is available to automatically enable or disable asynchronous operations during the GET or PUT operations. PROGRESS [ON:OFF] The PROGRESS Command will show a download/upload transfer indicator to show how many bytes were transmitted. Examples: Async On // open socket in async mode Open ftpsite // connect to ftpsite Progress On // turn on progress indicator Get /*.* \iFTP\import // download files ========================== iFTP Download File Caching ========================== iFTP offers built-in file caching when downloading files. What this means is that it is possible to download a file and try it again, and if the file is already in the cache, iFTP will not download it again. You can turn this behavior on or off with the iFTP.INI [Setup] session key UseCache=1/0 In addition, you can use the CACHE script command. CACHE ON|OFF New CACHE script command allows disabling/enabling of download caching. If off (default) all downloads are not saved on local drive cache. The main reason why you may wish to turn it off (default) is to conserve disk space. Cache is only required if you want iFTP to remember your downloads. Re-attempts of downloading the same file will be checked in the cache to see if the file is there. NOTE: The cache feature is a feature of the Microsoft WININET.DLL library. iFTP simply turns it on or off. iFTP itself does not have a cache system. ======================================================================= iFTP Set Variables, Internal, Environment Strings and Script Parameters ======================================================================= With iFTP scripts, you can define and use variables defined 4 different ways: - User Defined Set variables - Internal Variables always available - Environment Strings - Script parametners Variables are items that are defined and can used in scripts in a generic fashion. This featured concept is similar to DOS with its set environment strings and batch file parameters. They add tremendous programming power to your scripts by allowing you create scripts that are re-usable by others or yourself, and more maintainable. User Defined Set Variables -------------------------- Within iFTP scripts you can define variables called set variables or keys. Upto 30 set keys can be defined using the SET script command. To define a key, type SET key=value example: set file=whatever.zip To access the key, use the % character to surround the key, like so %key%. iFTP will substitute the value for the %key% when it is encountered in a script line. example #1: Write Ready to download file = %file% Get %file% example #2: set url1=http://www.santronics.com/iftp21.zip set url2=http://www.santronics.com/pxw20td.exe webget %url1% webget %url2% To erase a key, type SET key= To erase all keys, type: SETCLR To show all they keys or just one key, type: SET SET key Internal Variables ------------------ iFTP automatically provide some global variables to be used within your scripts besides the ones you can define. These global are always available to you: %input% Defined when the INPUT command is used %rashost% Currently connected RAS Host Entry Name %rasip% Currently connected assigned RAS IP Address %ftphost% Currently connected FTP host %errorlevel% Current ErrorLevel %lasterror% Last Error %lastkey% Last Key pressed (Ascii Code 0-255) %lastchar% Last Char pressed %script% Current Script Running %date% Current date in MM/DD/YYYY format, i.e, 06/28/1998 %time% Current time in HH:MM:SS format, i.e, 18:24:00 %day% Current day (abbreviation), i.e, Mon, Wed, Sat.. Example #1: Dial MyISP if not success then abort Log Connected to ISP! Assigned IP address is %rasip% Example #2: // // Dial ISP, and store IP address at your web site. // This allows other people to use a get the file // to see what your currently IP addrss is. This // useful for non-dedicated connections where you // might want to publish your 1 or 2 hour internet // connection // Dial MyISP if not success then abort Log Connected to ISP! Assigned IP address is %rasip% open ftp.mywebsite.com userid password if not success then abort write ftp:/assigned.ip %rasip% close Another iftp user can use this script to get the ip address. // // Get IP address and put it in set variable serverip // if exist assigned.ip then erase assigned.ip Webget http:://www.mywebsite.com/assigned.ip if not exist assigned.ip then abort "Service not alive" readfile assigned.ip serverip Log Server is available at IP address = %serverip% As you see, all kinds of iFTP programming power is available to you! Environment Strings ------------------- iFTP also supports the system environment strings within your scripts. For example: copy ftp:/usenet/*.* %import% The import environment string can be defined in a batch file and when you call the script, iFTP will translate the %import% environment string. Example: -- DoFTP.BAT --- @echo off set import=iFTP\import iFTP /run getfiles.ftp -- Getfiles.ftp -- Dial FtpSite if not success then abort Open FtpSite if not success then abort copy ftp:/usenet/*.* %import% Hangup iFTP Script Parameters ---------------------- Like batch files, you can pass up to 9 paramters to scripts. To access the script parameters, use %1, %2 ... thru %9. Do not use %1%. You can pass them via the iFTP command line: iFTP /run script [param1, param2...param9] or when calling a script with the CALL command: CALL script [param1, param2...param9] This adds tremendous programming power to your scripts making it possible to develop generic scripts with variables defined script parameters. Example: // File: PlayHalt.ftp // script to play wav file and halt playwav %1 halt 1 Now you can call this script like so: open ftpsite if not success then call playhalt badconnect.wav Comparing or Checking for Variables ----------------------------------- Whether you the set variables, internal environment strings or parameters, there are times where you have to check to make sure they exist. For this you use the IF condition EQUAL: IF EQUAL <string1> <string2> THEN ...... For example: if not equal "%ftpin%" "" goto ok Log Environment string FTPIN is not defined Log Please define it before calling this script Abort LABEL OK Use the double quotes around the string to make sure iFTP can read the two strings. If you don't use the "" then syntax would not be correct. The string comparison is not case sensitive. =============================================== Remote Access Service, Dial up Networking (DUN) =============================================== iFTP has a built-in Dial Up Networking (DUN) dialer. It works for Windows 95, Windows 98, Windows NT. Most people know it as RAS under Windows NT. +-[ NOTE ]-----------------------------------------------------+ | As of version 2.1C, you no longer need RAS installed on the | | computer to use iFTP. This is useful for pure LAN/WAN FTP | | server operations where RAS is not installed and no dialing | | is required from a workstation. | +--------------------------------------------------------------+ When iFTP first starts, it will always check to see if there is a current connection. This allows you to use iFTP with the current connection. If you attempt to dial when there is already a connection, iFTP will skip the dial command. You must hangup to dial again. There is two ways to dial with iFTP: - Using the iFTP /DIAL switch option - Using the iFTP DIAL script command Using the command line switch /DIAL: Syntax: iFTP /DIAL [entry] [userid] [password] The entry name must match one in the iFTP.INI file or in the DUN Phone Book in your system. If no entry name is provided, iFTP will use the default [PPP] account stored in the iFTP.INI file. The userid and password parameters are optional and can be stored in the iFTP.ini file. Under NT 3.51, it can stored in the DUN phone book. Only under Win95 or NT 4.0, is it necessary to store it in the iFTP.INI file. It is important to note that when using the /DIAL command, iFTP will not hangup. You must hangup the line yourself using a subseqeunt iFTP /HANGUP command. Examples: 1) iFTP /dial MyISP iFTP /run script iFTP /hangup 2) iFTP /dial /run script /hangup 3) iFTP /dial MySecondPPPaccount Using the DIAL Script command: DIAL [entry] [username [password]] The DIAL command will dial the entry name defined. The entry record must be created on your system. Under Win95, the entry is created with your Dialup Network Manager. Under NT, it is created with the Remote Access Server Manager. Under Win95 and WinNT 4.0, the username and password is required. Under WinNT 3.51, the username and password is not required. If no parameters are provided, the defaults are obtained from the iFTP.INI ([PPP] section). HANGUP Hangup the current RAS connection (carrier is drop). This is command is not necessary for a script. iFTP will automatically drop the line unless the DIALOPTIONS option /KEEP is used. DIALOPTIONS [/STATUS] [/KEEP] [/TIMEOUT <seconds>] [/REDIAL <amt>] The DIALOPTIONS command defines how the RAS dialing behaves. /STATUS This will show the dialing status information while it is dialing. This information can be very verbose. To minimize your iFTP.LOG file, do not use this option. Only use it when you need to investigate the dialing status to your provider. /KEEP By default, iFTP will automatically hangup the RAS connection when it exits. You can also hangup using the HANGUP command in your scripts. However, if you want to write a simple script to dial a system and keep the RAS connection alive, then option /KEEP tells iFTP to not hangup when it exits. This is useful when you want to use iFTP to dial up a system and keep the line active for other applications to use. /TIMEOUT <secs> The timeout option defines how long the dialer will wait before exiting with a time out ever. By default, the time out is 90 seconds. If you want to use Windows RAS default timeout value, then use 0 for the seconds. This will set an infinite wait value and will allow Windows to inform iFTP when it is complete. Normally, this is about 3-5 minutes under Win95/NT. /REDIAL <amt> The redial option is not implemented yet. Examples: ; Dial the default PPP account, show dial status, timeout in ; 60 seconds if fails to connect DialOptions /Status /Timeout 60 Dial if not success then abort ... hangup =========================== Session/Connection Commands =========================== OPEN [host or alias] [userid] [password] Opens a session with the remote ftp host site. If no parameters are provided, defaults are taken from iFTP.INI file. It is a good idea to use the IF condition to determine the success of the open. For example: Open ftp.microsoft anonymous hector@santronics.com If not success then abort If a session is already open, when this command is issued, the current session will be automaticalled closed. iFTP will always close a session (and the socket) when it exits back to the system. You can define an alias in the iFTP.INI file to get the parameters of the connect and login. For example: OPEN WebSite iFTP will search for the section [WebSite] in the inifile and read the host, userid and password key values. Using aliases makes it easier to design generic scripts to distribute to others without putting your userid and password in the scripts. If no alias is found, iFTP will assume the name to be DNS host name and attempt to resolve it. You can also use iFTP within a LAN where there is a FTP server. Simply type in the FTP server machine name and it will be found. You can also type in IP addresses as well. CLOSE Closes current session. QUIT Closes current session and exits script. When scripts are finished, iFTP will automatically close the session and close the socket. So CLOSE and QUIT are not necessary. CLOSE is only useful if you are OPENING and CLOSING multiple sessions in the same script. =============================== Directory and File I/O Commands =============================== iFTP was designed to offer a rich set of FILE I/O commands similar to that of DOS. All of the following commands work with either the local drive or the remote drive. To work with the remote directory, use the special FTP drive letter (ftp:) or the respective / or \ characters to distinquish direction. DIR [file spec] LS [file spec] Display files spec. LS displays the files in wide format similar to the unix format. Examples: Dir c:\bin\*.* Display files in c:\bin Dir ftp:/bin\*.* Display files in remote \bin directory. CD [directory] Change directory. If no directory is provided, the LOCAL current directory is displayed. To display the REMOTE current directory use ftp:. Examples: cd display local current directory cd ftp: display remote current directory cd ftp:/ return to remote root directory cd ftp:/inbin change to the remote /inbin directory MD <directory> MKDIR <directory> Make a new directory. Use the ftp: drive letters to indicate a remote directory. Examples: md \new create new local \new directory md ftp:/new create new remote /new directory RD <remote directory> RMDIR <remote directory> Remote directory. Use the ftp: drive letters to indicate a remote directory. Examples: rd \new remove local \new directory rd ftp:/new remove remote /new directory ERASE <remote filespec> DEL <remote filespec> Deletes one or more file(s). Use the ftp: drive letters to indicate remote files. Examples: erase \import\*.zip delete files in local import directory erase ftp:/import/*.zip delete files in remote import directory BINARY [ON:OFF] For file transfers, you may define how file transmissions are to be uploaded or downloaded using any of the file transfer commands. BINARY is enabled (ON) by default. If BINARY is disabled (OFF), then all files will have the linefeed character converted to carriage return/linefeed pairs during downloads and vice versa during uploads. This is considered a text mode transmission. Use Binary OFF when you are absolutely sure you are transferring text files only, such as *.txt or html files. Make sure binary mode is disabled when transmitted binary files such as ZIP files, Fidonet mail bundles or packets, etc. GET <remote filespec> [local storage path] [/KILL] Downloads remote files. If operation local storage path is defined, this is where the files will be locally stored. If the /KILL option is defined, the remote file is deleted after a successful download. examples: ; download remote files into current directory, kill remote ; file after each successful download get /export/*.zip /kill ; download remote files into storage directory get /export/*.zip \import see COPY, MOVE command PUT <Local filespec> [remote storage path] [/KILL] Uploads local files to the remote site. If operation remote storage path is defined, this is where the files will be remotely stored. If the /KILL option is defined, the local file is deleted after a successful upload. examples: ; Upload local files in current directory, kill local file ; after each successful upload put c:\pxw\export\*.* /kill ; Upload local files into remote directory. put c:\pxw\export\*.* /import /kill see COPY, MOVE command COPY <sourceFiles> <targetpath> MOVE <sourceFiles> <targetpath> Copies or moves one or more files from the source to the target. These commands offer you the DOS like similarities of the DOS copy and move commands. The move command is basically like the PUT -KILL options where it will copy the file and then delete it. This is useful in situations where they might be a connection drop. On restart, only the remaining files will be uploaded. examples: ; Copy local files to remote system copy \iFTP\export\*.* /import ; Move local files to remote system move \iFTP\export\*.* /import RENAME <OldFileName> <NewFileName> The RENAME command will remame the old file name to new file name. Both files must be on the same machine. When using DOS files, the new file name can be on a different directory or dos drive. So effectively, you can use this as a move operation with the ability to rename the file at the same time. For example: rename c:\file1.txt d:\backup\file3.txt When working with remote files on a FTP server, there might be some FTP servers who may or not honor the concept of moving a file when using the rename command. Be aware that some FTP servers, may not allow operation. For example: rename /file1.txt /textfiles/file20.txt The above command may work for FTP some servers. UPDATE <RemoteFiles> [DosPath] [-kill] The Update command allows you to download Remote files which are newer than the local files with the same name. If the local file does not exist, the files are copied. The UPDATE command works by using the remote file date and compares it with the local file date. So even of the option INI UseSaveDate is disabled, Update can be used to copy updated ftp files to the local drive. The -kill option works like the move. Updates remote files will be downloaded and then deleted from the remote site. NOTE: The Update command only works in one direction (Remote to Local). It does not work updated local files to the remote site. Consider using the XPUT command archive option. examples: ; Copy only new files from remote site update /reports/*.* \reports XPUT <LocalFiles> [Storage] [-A -M -E -T] XPUT is a very powerful command. It is similar to the DOS xcopy command but for putting (uploading) files to the remote site. Using XPUT without the options makes it work like the normal PUT command. But when used with options, you can perform massive copies including subdirectories from the local drive to the remote site. -E Copy files including subdirectories. New directories on the remove site will be checked and/or created. -A Copy only archive files to the remote site. Archive files are local files which have the archive bit. The archive bit is always set by the PC file system when the file is first created or modified. -M Same as -A but will remove the archive attribute of the file after the upload is finished. This is useful for backups or for mirroring a directories. The next the the XPUT -M command is used, it will only copy the new files. -T This option is used for TESTING purposes. It gives you the ability to see what XPUT will do when copying files without actually performing the copy. Use -T to see that it will do what you want first. Examples: ; Copy the entire local web directory and subdirectories ; Run in test mode to see the results first. xput j:\website\*.* ftp:/ -e -m -t WRITEFILE <file> [string] This command opens a file and writes the optional string to it, then closes the file. This command is useful for creating a semaphore file like it is done in the PAONLINE.FTP example. READFILE <filename> <var> [line#] Read a line in the file and set the result into the variable "var". The variable can then be used as a set variable. ================ Generic Commands ================ STATUS Show iFTP Status Information. This command will display the current state of affairs with internal information such as RAS or IP connections, asynchronous or synchronous states or debugging states and so on. It is useful to use during console mode when you are testing your scripts. Here is an example output: * iFTP Status Information: * RAS Connection : Vincent * RAS IP Address : 209.4.200.151 * RAS Connect Time : 1232 secs * FTP Connection : <no connection> * Socket Mode : Sync Dial Mode : Sync * Connect Mode : Sync Search Mode : Sync * Download Mode : Sync Upload Mode : Sync * Save File Date : OFF Transfer Type : Binary * Download Cache : OFF Show Progress : ON * Server Debug : OFF Async Debug : OFF * Script Debug : OFF Verbose Debug : OFF * Show I/O Errors : OFF Error Level : 0 * Last Error # : 0 System Error : 0 * Last Error Msg : The operation completed successfully DEBUG [ON|OFF|LOG|ASYNC|SCRIPT] Turns on/off the debugging of scripts, verbosity of the log file and the result of asynchronous communications. This is only useful under debugging situations. BEEP Sound the speaker PLAYWAV <file> This allows the playing of wav files (Sounds card required). Useful for signaling certain events. Example: open ftpsite if not success then playwav BadConnect.Wav See the provided SOUND.ZIP for example wav files that can be used with your scripts. POPUPMSG <string> Display a POPUP Messages. It is a simple OK buttom message box. Useful to pause the script for certain events. EXEC <application> DOS <application> This command will start the application specified. DOS does the same thing but will use the DOS command interpreter to run the application. Use DOS when you want to use DOS commands within scripts. Examples: ; Run dos command dos ping ftp2.paonline.com CALL <scriptfile> Runs another script file and return the calling script. This is useful for running multiple scripts during the same iFTP execution. Example: Suppose you have two independent scripts; script1.ftp, script2.ftp, you can do this: iFTP /RUN script1.ftp iFTP /RUN script2.ftp or you can create another script called runall.ftp which has the following lines: call script1.ftp call script2.ftp and run iFTP once by doing the following: iFTP /RUN runall.ftp ABORT [string] Aborts the current script and exits iFTP. If optional string is provided, it is written to the log and screen. A process error level of 1 is set. This process error level can be detected by a batch file. HALT [errorlevel] Similar to the ABORT command, but allowing you to define an process error level. This process error level can be detected by a batch file. See example #6 (exam6.ftp) EXIT [errorlevel] Exits current script, exits iFTP or calling script with optional errorlevel. EXIT simply exits the current script and returns to the calling script. If its the top script, then iFTP ends. With the optional errorlevel, you can use this to test scripts errorlevels, for example: main script: call subscript ftpsite *.* if errorlevel 1 then Abort "Bad Connection!" if errorlevel 2 then Abort "Bad Download!" Log Success! Exit 0 subscript: open %1 if not success then exit 1 get ftp:/%2 if not success then exit 2 Exit 0 ERRORLEVEL [errorlevel] Change the current error level as remembered by IFTP. ERRORQUIET [ON|OFF] Enable or disable the internal I/O error logging. By default, iFTP scripts commands will be quiet, like GET /*.*. This allows you more control with your scripts to log the results yourself. See the IF ERRORQUIET discussion below. GOTO <label> Jump to the label provided. See LABEL command LABEL <label> Defines a label in the script file. Example: open ftp.microsoft anonymous hector@santronics.com if not success then goto error . . LABEL error IF [NOT] <condition> [THEN] <commands> or IF [NOT] <condition> [THEN] BEGIN [ELSE] ENDIF The IF command sets up a conditional check. If true, the rest of the line is read. If false, the next line is read. The optional NOT word provides a negative conditional check. The THEN word is not necessary, but it makes the script easier to read. In additional, you can use the word AND to add more conditions. for example: example: if not success and errorno 12007 then write Open Fail! Check PPP! You may also use the structured IF BEGIN ELSE ENDIF block. If you want to use a block, then the IF line must have the BEGIN word and you must have a matching ENDIF command. The ELSE is optional which will executure the FALSE portion of the condition. The following conditions are supported: ERRORNO <errorno> Checks/Compares the errorno with the last error number defined by the previous command. ERRORLEVEL <errorlevel> Checks/Compares the errorlevel with the current errorlevel set in the scripts. SUCCESS Compares the success operation of the previous command. CARRIER Carrier is true if the PORT is active. ERRORQUIET ERRORQUIET is true by default when running scripts. This prevents I/O commands from logging errors thus given you more error logging control via scripts. By using a IF ERRORQUIET check, you can conditional write errors to the log based if it hasn't been written to the log yet by the internal error logger. In short, if you want to minimize scripts by not using commands such as: get /*.* if not success then writeerror Then set ErrorQuiet to NO or FALSE, and the GET /*.* will write the error to the log and screen for you. Example: // Take control of error logging by making the I/O // command quiet. By turning off the internal // error logger, if you want to see errors written // to the screen and the log file, then you have // to use the WriteError command yourself. ErrorQuiet On get /*.* if not success then writeerror // Allow the internal I/O error logger to write // errors to the screen and log. This avoids // the duplicate writing yourself. ErrorQuiet Off get /*.* if not success then abort // Make the error logging conditional by using // IF ERRORQUIET. This allows you to turn the // error logging on and off at the top of your // scripts and still maintain a generic script // This is good for debugging situations where // you want to catch all possible errors. ErrorQuiet Off get /*.* if not success then begin if ErrorQuiet then WriteError Abort endif SESSION Session is true if the current connection is active. The OPEN command establishes a session. EXIST <filespec> Checks if file(s) exist example: ; Download remote outbin files, if any, into the current ; directory If Exist ftp:/outbin/*.* then Get /outbin/*.* /kill EQUAL <string1> <string2> Compares two strings. Useful to change set variables and environment strings. example: ; Check to make sure the environment string FTPOUT is ; defined before continuing. If not equal "%ftpout%" "" then Abort SET FTPOUT not defined TIMERANGE <begintime> <endtime> Compares the current time within the begin and end time. This is useful when you want want to run a part of a script during a certain time of the day. example: ; Run this part of the script when the time is between 5pm ; and 7pm on Wednesdays only! If EQUAL "%day%" "Wed" then begin If TIMERANGE 17:00:00 19:00:00 then begin Log Starting Special Section...... endif endif LOG <string> Writes to the screen and log file the string WRITE <string> ECHO <string> Write/echo string to the screen. The string is not written to the iFTP log file. WRITEERROR [string] Writes to the screen/log the last error number recorded example: ; Upload local files to the remote site, if any, into the ; remote \inbin directory open ftp.microsoft anonymous hector@santronics.com if not success then goto error if exist index.txt then get index.txt goto end Label error writeerror Fail to open ftp site Label End WEBGET <http url> [storage] URLGET <any url> [storage] iFTP now offers the ability to download web files using the WEBGET or the URLGET commands. The difference between the two is that URLGET supports the standard URL naming format, while WEBGET is used for simply anonymous http:// web site downloads. Examples: Webget http://www.santronics.com/iftp20.zip urlget ftp://ftp.site.com/pub/whatever.zip urlget ftp://username@password:ftp.site.com/pub/whatever.zip Also URLGET can not be used under NT 3.51 in asynchronous mode. ==================== Timers and Scheduler ==================== DELAY <milliseconds> [SECS|HOURS|MINS] Forces the script to pause for the amount of milliseconds defined. If no adjective is used such as secs, hours, mins then milliseconds is assumed. All forms and abbreviations for the adjective is acceptable. i.e., hrs, mins, secs, etc. Examples: Delay 1 hour Delay 60 seconds Delay 30 minutes TIMEOUT <seconds> Creates a global timer. If the timer expires before script is finished, then the script will be aborted. This is typically not necessary until you have a situation where you know the script should finish within a known time frame but does not. Example: ;Setup global 1 hour timeout (3600 seconds in 1 hour) Timeout 3600 WAITUNTIL <hh:ss or nexthour> Creates a schedule to wait until the specific time has been reached. The script is paused (in idle state) while the waiting occurs. If the time is the special keyword "NEXTHOUR" then it will wait until the next hour is reached (waits 60 mins). This is good for a continue script system who wished to be process every hour. The time must be in military time. Examples: ;Setup a schedule for 10:00pm WaitUntil 20:00 if not success goto wait_aborted ;Setup a schedule for each hour WaitUntil NextHour if not success goto wait_aborted ================================ iFTP Interactive Script Commands ================================ +----------------------------------------------------------+ | NOTE: This feature has been removed in the iFTP v2.0 | | release due to Operating System incompatibility issues. | | Some of it works under 95 and not under NT while other | | items behave correctly on NT but not on 95. So it has | | been removed until it can be fully tested and designed | | for all OSes. | +----------------------------------------------------------+ iFTP has been enhanced with a new interactive keyboard script commands which will allow you to create sophisticated interactive scripts. Interactive scripts allow you to have a "dialog" or "conversation" with the script to make intelligent choices. The new commands are: CLS CLS is equivalent to the DOS CLS command. It clears the screen putting the cursor at the top of the screen. READKEY Readkey can be used two modes: - as a command to receive a character - as part of the IF condition to read a character and automatically compare it with another character. In either mode, Readkey waits for a single character to be pressed. iFTP will remembers the "last key pressed" so that it can checked using IF READKEY or the IF LASTKEY condition. See IF LASTKEY description and example. CHOICEKEY <chars> [timeout] ChoiceKey waits for a characters <chars> with an optional time out value. <chars> can be any single group of characters. Case Insensitive. To use special control characters like escape or carriage return, use the mnemonics provided. See the table of mnemonics in the appendix. If no timeout is provided, the wait is infinite (forever). If a timeout is provided and the timeout is reached, the default character returned is the FIRST character. ChoiceKey will beep if the wrong character is hit. Examples: // wait for option Y or esc Write "Press Y to continue, ESC to abort: " ChoiceKey Y<esc> // Wait for option, abort if 10 secs is reached Write "Press Y to continue, ESC to abort (10 secs abort): " ChoiceKey <esc>Y 10 secs IF LASTKEY <char> This new if condition allows you to check the result of the readkey or choicekey script commands to see which key was pressed. <char> is the single character you wish to check. You can also use a mnemonic. A mnemonic is a special <xx> character that represents a value between 0-31, often known as the ASCII control codes. See the appendix for the table of mnemonics recognized by iFTP. Examples: // // Ask user to press the ENTER key, check the last key // by using the mnemonic <cr>. <cr> happens to be 13 // so 13 can be used instead. // Writeln "Press ENTER to continue" readkey if not lastkey <cr> then begin beep abort "Next time hit ENTER!" else writeln "Good Boy! Let's continue" endif // // Ask for Y or N. Default to Y if no key is pressed // within 30 secs. // Write "Press N to Stop, Y to continue" ChoiceKey YN 30 secs if LastKey N then quit IF READKEY <char> This command combines the ReadKey and IF LastKey commands. Example: // // Using Readkey and IF Lastkey // ReadKey if lastkey <cr> then writeln Enter was hit if lastkey Y then writeln Y was hit // // Using If Readkey only // if ReadKey <cr> then writeln Enter was hit if lastkey Y then writeln Y was hit Once you use Readkey, iftp will remember the last key so you can only use IF LASTKEY if you wish to compare the result with other characters. So IF READKEY simply combines two commands into one. IF KEYPRESSED This new if condition allows you to check if a key was pressed. The key remains in memory until the next readkey or choicekey is called. This is useful for creating loops where you might want to do something on a continous basis but check for an "escape" Example: Label Again: Call CheckForMail If keypressed then if readkey <esc> then exit goto again ============================== Using iFTP in Console Commands ============================== iFTP now offers a manual, interactive console mode. This allows you to to type iFTP script commands in a manual mode instantly seeing the results. This is useful when you want to quickly start a ftp session and perform a few commands. To start iFTP console mode, run iFTP with the /CON switch: iftp /con Once in the console mode, you will be greeted with a prompt "dos:>" where you can begin typing in commands. The prompt "dos:>" has a special meaning. Since iFTP was designed to have script FILE I/O commands which can be used in transfer files in either direction depending on the source and target file names, the dos:> signifies iFTP "frame of reference" is relatively to the local machine current drive and directory. For example, if you type "dir" at the dos:> prompt, dos:> dir The dir command will assume the local drive and display files in the current directory of the local machine. However, you can switch iFTP's "frame of reference" to be relatively to the remote ftp directory by using the FTP: command. Once you use the FTP: command, the prompt will change to "ftp:>". Now the DIR will assume the remote drive first. By using the FTP: drive switch command, it it now easy to use commands like CD, DIR, MD, RD, etc. For example: dos:> cd << show local drive current directory dos:> ftp: << switch to remote drive ftp:> cd << show local drive current directory ftp:> cd usenet << switch to the remote usenet directory ftp:> dir << show files in remote usenet directory ftp:> dos: << switch back to local drive dos:> copy *.* ftp: << copy local files to remote current directory In console mode, there are other commands available to you. In addition, the following are available: Help [command search] Show help during console mode Rep [history index] Repeat last or history index item Hist [CLEAR] Show or clear history of commands Edit <file> Call defined editor to edit file Status Show iFTP internal state information ftp: Switch to remote drive dos: switch to local drive Among typical manual iFTP sessions what can be done in iFTP console mode, another useful operation would be to create/edit scripts within console mode so that you can quickly test them. Example: dos:> edit ftpsite.ftp << edit or create script ftpsite.ftp dos:> call ftpsite << test script dos:> status << show status inforation ======================================================== APPENDIX A: iFTP Script Command Summary Reference Table ======================================================== Remote Access Service --------------------- DIALOPTS [/STATUS] [/KEEP] [/TIMEOUT <#>] Define Dial Options DIAL [entry] [username [password]] Dial a PPP system HANGUP Hangup/Drop Carroer Connection, File I/O -------------------- OPEN [host/alias] [userid] [password] open session CLOSE close current session QUIT close session and quit script DIR [file spec] display directory files CD [directory] change directory MD <directory> create directory MKDIR <directory> create directory RD <directory> delete directory RMDIR <directory> delete directory ERASE <file(s)> delete file(s) DEL <file(s)> delete file(s) GET <remote file(s)> [storage] [-KILL] download files PUT <Local file(s)> [storage] [-KILL] upload files COPY <sourceFiles> <targetpath> copy source files to target path MOVE <sourceFiles> <targetpath> move source files to target path RENAME <OldFileName> <NewFileName> rename file name UPDATE <RemoteFiles> [DosPath] [-kill] Copy updated remote files WRITEFILE <file> [string] write string to file DEBUG [ON|OFF|LOG|ASYNC|SCRIPT] enable script debugging CALL <scriptfile> [parameters] call another script ABORT [string] aborts script and exits HALT [errorlevel] aborts script w/ errorlevel EXIT [errorlevel] exist current script GOTO <label> jump to label in script LABEL <label> defines label in script LOG <string> writes string to log/screen LOGFILE [filename] change script log file WRITE <string> writes string to screen WRITEERROR [string] writes last error DELAY <milliseconds> pause/delay TIMEOUT <seconds> Create Global Timeout WAITUNTIL <hh:ss or NEXTHOUR> Wait until time hh:ss or next hour EXEC <application> Spawn or start application DOS <dos commands or application> Like exec, but uses COMPSEC STATUS Show Status Information SET [key[=value]] Show/Set/UnSet local variables SETCLR Clear all local variables WEBGET <http://site/filename> Download http (WEB) only file URLGET <Url> Download generic URL file READFILE <filename> <var> [line#] Read local file into variable LS [spec] Show directory in wide format CACHE [ON|OFF] Toggle Download Cache (OFF) BEEP Sound PC beeper SERVERLOG [ON:OFF] Log FTP responses to iftpserv.log BINARY [ON:OFF] Toggle Transfer Binary or Ascii ERRORQUIET [ON:OFF] Toggle I/O Error Display/Log SAVEDATE [ON:OFF] Use Remote Date for downloads PLAYWAV <wavfile> Play wavfile (soundcard required) POPUPMSG <string> Display window popup message ASYNC [ON|OFF] [ALL|CONNECT|GET|PUT|DIR] Toggle specific async modes PROGRESS [ON|OFF] Transfer Progress Indicator FTP: Switch to Remote FTP drive DOS: Switch to Local DOS drive TYPE <file> Display File to Console/Screen XPUT <LocalFiles> [Storage] [-A -M -E -T] Upload Files with options Help [command search] Show help during console mode Rep [history index] Repeat last or history index item Hist [CLEAR] Show or clear history of commands Edit <file> Call defined editor to edit file CHOICEKEY <chars> [timeout] Keyboard Input w/ timeout READKEY Keyboard input CLS Clear the screen Conditional Script Processing ----------------------------- IF [NOT] <conditions> [THEN] <commands> conditional processing or you can use structured blocks like so: IF [NOT] <conditions> [THEN] BEGIN <commands> [ELSE] <commands> <....> <commands> ENDIF To use a structured block, the last word on the IF line must be BEGIN and there must be a matching ENDIF. Nested blocks are supported. The only reason for structure blocks are is to eliminate the need to use goto statements. The conditions parameter can be any one of the following: ERRORNO <errorno> check last error SUCCESS check last success CARRIER check RAS carrier SESSION check current session ERRORLEVEL <errorlevel> check error level ERRORQUIET true/false I/O error loggin EXIST <filespec> check remote/local file EQUAL <string1> <string2> compares two strings LASTKEY <char> compares last key hit w/ char READKEY <char> read/compare a key w/ char KEYPRESSED check if key was pressed ============================================== APPENDIX B: iFTP Ascii Control Code Mnemonics ============================================== The Ascii key code vs Mnemonics table shown below are string representations for the first 0-31 ascii control codes. Ascii code 32 (space) is not really a control code, but since it is difficult to represent a "space" other than the real thing, it is given a mnemonic as well. In iFTP, mnemonics has very limited usage. Most of the mnemonics will not be useful to you since they really only have special meaning in certain areas which iFTP has nothing to do with (like printers). However, a few do come in handy when developing interactive scripts with keyboard script commands such as: ReadKey ChoiceKey if LastKey <char> if ReadKey <char> For example if you wish to trap the "escape" key, then you can use the ascii key code 27 or the mnemonic <esc>. Example: ReadKey if LastKey <esc> then Abort "Script Aborted!" or Write "Press Y to continue <esc> to abort: " ChoiceKey Y<esc> if LastKey 27 then Abort "Script Aborted" Mnemonics like <esc>, <cr> will probably be among the most often use if you create interactive scripts. Ascii Key Code Mnemonics -------- --------- 0 <nul> 1 <soh> 2 <stx> 3 <etx> ctrl c 4 <eot> 5 <enq> 6 <ack> 7 <bel> bell 8 <bs> backspace 9 <ht> 10 <lf> line feed 11 <vt> 12 <ff> form feed 13 <cr> carriage return 14 <so> 15 <si> 16 <dle> 17 <dc1> 18 <dc2> 19 <dc3> 20 <dc4> 21 <nak> 22 <syn> 23 <etb> 24 <can> 25 <em> 26 <sub> 27 <esc> escape 28 <fs> 29 <gs> 30 <rs> 31 <us> 32 <sp> =========================================== APPENDIX C: iFTP Diagnostics =========================================== This section offers some ideas and tools that you can use to address potential issues and problems when dealing with the Internet and with iFTP. First, Internet Developers would like to make a small point about a known fact when it comes to the writing software for the internet: "Nothing is guaranteed delivery" Let me explain: iFTP was designed with lots of detail attention to performance and reliability. Performance is iFTP's responsibility. Much of the reliability is dependent on Microsoft's Socket Libraries offered to software developers to write internet software. The socket libraries are the key to talking to the internet using what is call TCP/IP. For the most part, Microsoft's Socket libraries are pretty good in the area of reporting errors to the best of its ability. If there is an internet error and this is an important concept, it has to be a "detectable" error, the socket libraries will report them back to the application (iFTP) and at the point, iFTP will do what it thinks is best for the situation. But once again, all developers know one thing is guaranteed with the internet: "Nothing is guaranteed delivery" In short, what that means is if data is sent to the internet and it has to properate thru a chain of ROUTERS to reach a destination, you can not guarantee that it will reach the destination and you can not quarantee you will get an "detectable error". What is guaranteed by the internet is if and when data finally reaches a destination, it guarantees that it is correct and intact. So what are we talking about here? We are talking about Server Availability, ISPs being down, Connection Drops and transmission time outs. The best the Socket Libraries and for the most part what the Internet can offer are "time outs". iFTP offers some tuning options to set the different timeouts so that iFTP does not get hung in certain areas with the long default timeouts. Some of the default times can be as long as 5 to 15 minutes. The section [Wininet] in the INI file offers some key options you can set to change the default timeouts. The lower the value, the faster the responses. Keep in mind that it is very possible to get a signficant delay when transfering a file that can be as long as 1-4 or more minutes. But that is your judgement call based on your particular knowledge on your specific connection points as to how the sessions typically perform. Once again, if the internet reports errors to the Windows Socket libraries, and in turn the socket libraries report errors to iFTP, iFTP will be able to track these errors and offer the result to you for proper script control. Here are some Win95/NT tools that are available on your machine which you can use to perform some diagnostics: Ping [address or dns name] Ping is low level internet protocol which is basically used as an error tool to "ping" the site to see if its alive. Errors are based on "time outs" so if you ping a site, it will either time out or respond. All computers on a TCP/IP network will respond to a ping (unless there is a firewall protecting the site). When they receive a Ping, the machine is suppose to basically "echo back" the same information sent to it. So if the sender does not get the information back within a certain "Time To Live" (TTL) value, you will see a Timeout error on the screen. If the machine is responsing, you will see some clean information about the ping. examples: ping ftp.microsoft.com ping ftp2.paonline.com ping www.santronic.com Finger [user@address] or [@address] Finger is another diagnostic tool. Basically it is used to see the users "logged into a system". But don't depend on the information being sent to you. Typically what you will see, is the "intro" screen for a particular site. examples: finger @ftp2.paonline.com This will probably just display the ftp welcome screen. It depends on the ftp site. finger @ntserver If you are on a TCP/IP LAN network and the server machine is called ntserver, you can finger it to see if the ftp server can show you some information. If you are using for example, Mustang's Winserver and you have the FTP server enabled, Winserver will show you all users who are logged on, just like WCNODE will show. tracert [address or dns name] Tracert is probably the best tool you have to see the routing of information from your computer to the final destination address. You will be surprise (and maybe even disappointed) to see how your information can go thru a long list of systems before it reaches the end point. It all depends on how your ISP is connected to the internet and his higher ISP is connected to the internet, and so on down the line. If it seems that there is a problem somewhere in the loop, use tracert to see where in the loop the backlog or a broken connection is at. Sometimes you can blame your ISP for being down. But tracert may prove otherwise, it may be his provider or the next provider down the link. You see, this is why the axiom: "Nothing is guaranteed Delivery" is so true on the internet. There are so many things that can go wrong and there is so much dependency on everyone in the loop working properly, that you will don't have a true way to send data and make sure the destination got it without asking him he if did get. I hope this has provided some insight on the complexity of the internet and writing software for it.